t MultiUser Access to Datafile Manager  *489*

Datafiles created with the Prograph Datafile Manager can be accessed by multiple users if opened in Shared mode (see the description for db-open primitive later in this chapter). To make this possible, the datafile must reside on a shared volume within an AppleTalk network.

Applications that open a shared datafile must be aware that other applications may be accessing that datafile. From a programmer’s perspective, the following items must be considered when accessing a datafile:

1.	To replace an existing cluster, lock the cluster, call cluster, replace, then unlock the cluster.

2.	Attempting to read a cluster may result in an error indicating that someone else has locked the cluster; you may try again later;

3.	It is not necessary to explicitly flush a shared datafile, since all shared datafiles are flushed automatically after each write.

Locking and Unlocking Clusters  *490*

In a shared datafile, multiple users can read a cluster simultaneously; however, only a single user may safely overwrite a cluster. For this reason it is necessary to lock a cluster before writing to the datafile, to prevent another user from writing to the same cluster at the same time. After an application has overwritten a cluster, the cluster should be unlocked to allow other users access to the cluster.

_______________________________________________________
NOTE:

When a user locks a cluster, that cluster cannot be overwritten or even read by another user until it is unlocked.
--------------------------------------------------------

To lock a cluster, call the cluster-lock primitive. This primitive must be supplied with the following:

r the table id number, and

r the cluster id number. 

cluster-lock locks a cluster, thus preventing other users from accessing it, and returns an error number indicating whether or not the primitive succeeded.

To unlock a cluster, call the cluster-unlock primitive. This primitive must be supplied with the following:

r the table id number, and

r the cluster id number. 

cluster-unlock unlocks a cluster, allowing other users to access it, and returns an error number indicating whether or not the primitive succeeded.

The following sample method locks a cluster before replacing it, and then unlocks the cluster: